Monkey Documentation

Getting started

Hi and welcome to Monkey!

Please read this article fully. Monkey does certain things a little differently, so this article will attempt to cover all those 'gotcha' things that you may encounter when getting started.

Installation

After installing Monkey, you should be able to build and run programs for at least the Html5 target. If you are having problems running Html5 programs you may need to upgrade your browser.

To build for other targets, you will need to install the tools and SDKs required by those targets. For example, to build android apps you will need to install the android SDK.

Please see the Target SDKs page for more details.

The Monkey language

Monkey is a high level programming language based on the popular 'Blitz' range of languages, and was inspired by both Java for its streamlined language, and BASIC for its readability.

Monkey is also a translator - it translates programs written in the Monkey language into a number of different target languages, which in turn allows Monkey programs to run on a wide range of target platforms.

Once Monkey has translated a program into a form appropriate for a target platform, it then passes the program on to the native tools and SDKs used by the platform to complete the compilation and linking process. Therefore, before using Monkey you will need to ensure the correct tools and SDKs used by the various target platforms are installed. Please see the sections at the end of this document for instructions for installing target platform SDKs.

Please see the Language reference section for a description of the Monkey language.

Monkey quick tips

  • Monkey source files must have a '.monkey' extension.

  • All Monkey programs must have a single Main() function that takes no parameters and returns an int. This is where program execution begins. If you are using the Mojo modules, you will need to create an instance of the App class inside main.

  • All program statements in a Monkey program must appear inside a function or method declaration. This differs from earlier Blitz languages that allowed you to have program statements in the main body of a program/module.

  • When a Monkey program is translated with the trans tool, the output is placed into a special 'build' directory. This directory has the same name as the program's main source file, only with a '.build' extension instead of '.monkey'. You are free to modify the projects and source files found in '.build' directories, only make sure to avoid modifying anything between any //${BEGIN.. and //${END...} tags found in any source files. This is where generated Monkey code/data goes, and is replaced every time you rebuild a Monkey app.

The Mojo module

Monkey also includes a lightweight programming framework called Mojo.

Mojo is designed primarily for writing simple 2D games. It is highly portable, lightweight, and mostly procedural in nature. It is in many ways designed for programmers like myself who just want access to the low level stuff as easily as possible!

Mojo is most likely what you will use when you start programming Monkey, but it is not part of the Monkey language - it is an optional module, and in future other such framework modules may also appear.

Mojo is freely available for the Html5 target, and may be licensed from Blitz Research Ltd for use on the Glfw, Android, iOS, Xna, Psm and Win8 targets.

Mojo quick tips

  • Mojo applications must extend the Mojo App class and create a new instance of this class somewhere inside the Monkey Main() function. This is what actually creates the application.

  • All data for Mojo programs (images, sounds and text files) must go into a special data directory. This directory has the same name as the program's main source file, only with a '.data' extension instead of '.monkey'. For example, if your main source file is called 'joust2k.monkey', then your data directory should be name 'joust2k.data'.

  • Mojo functions should not be called until your application's OnCreate method is called. This means you cannot initialize global variables with values returned by Mojo functions such as MilliSecs - you must instead initialize such variables in your application's OnCreate method or later.

  • Mojo is callback based, as opposed to earlier Blitz Research products where your application 'drove' the main loop. A callback based app instead responds to events generated by the underlying OS.

  • Mojo does not deal with resizing the display. This must be done on the target side of things, meaning that you will need to modify the target project in the program's '.build' directory. The exact process involved with resizing the display (and controlling display capabilities in general) varies greatly from target to target. It may involve editing some source code, or perhaps using a RAD tool to resize a window, which is why Mojo makes no attempt to deal with this side of things. Please see the notes in the various target platform docs below.